Contents

Click on  the desired menu button for specific help

Other Topics

The Editor	The special editor that creates help files.

The Keyboard	Function and Ctrl key definitions.

The Status Bar	Displays the attributes of the text and current page.

The Utility Area	Keywords, Multiple Keywords, Browse, and Context Number.

Test Mode	Test the help system.

Tool Bar	Marker functions plus.

How To...	Help on How To...


Editor
The Editor

The Editor, provided with the Help Magician, provides all of the functions necessary to build a complete Windows help system. The special Markers, used by the Help Magician, are easily inserted into the help text by selecting the appropriate menu item or by pressing the hot key.

Functions are provided to search for and, optionally, replace text. Both search and replace include options for case sensitivity, whole word, current page, or entire help file.

Help text can be cut or copied to the Windows Clipboard. Text can be pasted from the Clipboard into the help text.

Pages can be inserted into or deleted from the help file, and the Marker database is updated as the functions are performed.

You can Jump to a particular help topic by title or page number.

The Editor is always in insert mode and characters will be inserted into the text rather than overwriting existing text. Several methods of deleting text are provided and text can be overwritten by highlighting it and entering the new text.

The Tab key moves the focus between controls on the form so it cannot be used to enter a tab character into the text. Use Ctrl Tab to enter a tab character.

Pages/Topics

There is a limit of 512 pages in a help file. The help file is limited to 1,024,000 characters, or 1 megabyte. This translates to a Windows help file of about 1 1/2 megabyte because there is approximately a 150% increase in size after compiling. The 1 megabyte help file limit is divided equally among 16 groups of 32 pages each, providing 64K of memory for each 32 page segment.

Related Topics

Editor Menu

Edit Menu

Marker Menu

Keyboard


Inserting Tabs

The Tab key move the focus from on form control to another and cannot be used to inset a Tab character into the help text. Use the Ctrl Tab key combination to enter a tab character.


Inserting Markers

Markers are inserted in the help text by placing the cursor on the desired word or by highlighting a number of words and selecting the appropriate Marker type from the Marker Menu.

Selecting Text

Single words or phrases can be selected and marked. Text for all of the Marker types is chosen in the same manner and the selection procedure is quite liberal. If the cursor is on any part of a word, or the space before a word, the entire word is included when the Marker is selected. If text is highlighted, the highlighting need not cover the entire phrase from beginning to end.

Punctuation

The Marker will be placed in front of the first word in the phrase and at the end of the last even if they are not completely highlighted. Any punctuation mark will be considered a word delimiter and Markers will be placed inside the punctuation except for punctuation inside highlighted text.


Deleting Markers

Markers cannot be deleted with the backspace or delete keys. They must be deleted from the Marker Menu or with the Ctrl D hot key combination. Markers are referenced in a database and the database must be updated when they are deleted.

Deleting Markers

The function that deletes Markers determines which type of Marker the cursor is on. If Markers are nested, place the cursor just to the left of the Marker to be deleted. Use the Marker Type indicator in the Status Bar to determine what type of Marker the cursor is on.

Emergency Key

If, at any time, you cause an invalid nesting of markers that cannot be corrected or deleted with the Marker delete function (Ctrl D or Marker/Delete), individual markers can be deleted with the emergency delete key, Ctrl ] (Ctrl key + right bracket) key combination. This will delete the Marker to the right of the cursor. You will also have to delete its corresponding starting or ending Marker, if any.

Related Topics

Inserting Markers

Marker Menu

Status Bar


Keyboard

F1	Help

Ctrl F3	Find.

F3	Find Next occurrence of text specified in original search.

Shift F3	Find Previous.

Shift Ctrl F3	Replace.

F5	Project Options.

F4	Goto Title.

F6	Write RTF.

F7	Run Compiler.

F8	Rebuild All.

Shift F8	View Track List

F9	Call WINHELP.EXE.

Shift F9	Call Word Processor

Ctrl Tab	Inserts a Tab into the help text. The Tab key alone moves the focus to the next control on the form.

Ctrl A	Save As Text.

Ctrl B	Inserts a Bitmap Marker.

Ctrl D	Deletes any of the special Markers used by the Help Magician.

Ctrl F	Inserts a Font Style Marker.

Ctrl G	Deletes the current page (confirmation required).

Ctrl I	Import ASCII text into the help file.

Ctrl J	Inserts a Jump Marker into the text. Select topic to Jump to from a table of topics.

Ctrl L	Define Styles.

Ctrl P	Inserts a Popup Marker into the help text. Select page, to display as a Popup, from a table of topics.

Ctrl R	Reformats the text in the current help page with regard to word wrap.

Ctrl S	Save current help file without renaming if the help file already has a name other than DEFAULT.HLX.

Ctrl V	View/Modify Marker.

Ctrl Y	Load Styles.

Ctrl Z	Insert a new page into the help file.


Status Bar
The Status Bar

The Status Bar continuously displays the current page number and topic title. The Marker type, Jump, Popup, Font Style, Bitmap (C = Character, L = Left, R = Right Justification), Indent, and the attributes of the help text (as defined by the Font Style Marker) under the cursor are continuously updated. If the cursor is not between Font Style Markers, the attributes of the Default Font Style are displayed.

Click on  the desired area of the Status Bar for specific help

Related Topics

Marker Menu

Define Styles

Test Mode


Page
Status Bar - Page: Label

Text Box

The text box after the Page: label is continuously updated to reflect the current page number. A page number may also be entered into this text box to 'go to' any page. If a page number greater than the number of pages in the help file is entered, the editor will display the last page in the file.


Title
Status Bar - Title: Label

Text Box

The text box after the Title: label is continuously updated to reflect the title of the current page, or topic. You can edit the title by tabbing to or clicking on the text box. Titles can contain any ASCII characters except colons.

Automatic Topic Heading

Clicking on the Title button will cause the Help Magician to copy the contents of the Title text box to the top of the current page. If a font style (see Define Styles) named "Topic Heading" has been defined, the appropriate font markers will be placed around the topic heading.

Restore

Pressing the Esc key will restore the original contents of the Title: text box and return focus to the editor.


Status
Status Bar - Status: Label

Status Label

The Status label shows the type of Marker, if any, under the cursor. If the text under the cursor is not contained in Markers, the word Text is displayed in the label. The Marker possibilities are: Jump, Popup, Bitmap C, Bitmap L, Bitmap R, and Indent. Text is assigned Markers by selecting the desired text and placing the Marker with the appropriate Marker sub menu command or hot key.

Jump/Popup

If the Status label is displaying a Jump or a Popup, the page number, to which it is linked will also be displayed. Double clicking on the Status label will go to the page number indicated.


Font Label
Status Bar - Font Label

Font Name

The Font label is continuously updated to reflect the typeface of the text under the cursor. Text is assigned font attributes by selecting the Font Style Marker from the Marker Menu and selecting the Font Style from a list of pre-defined Font Styles. The font in the label is displayed with its defined attributes with regard to boldness, color, and whether the text is italicized or not.

Browse Group Limit

There is a limit of 100 Browse Groups in a help system.


Font Size
Status Bar - Font Size Label

Font Size

The Font Size label displays the point size of the text under the cursor. Since the text cannot be displayed in its actual size in the typeface label, the size is displayed here.


Utility Area
The Utility Area

The Utility Area, located just below the editor, is used to enter Keywords, Multiple Keywords, and Context Numbers.

Click on  the desired area of the Utility Area for specific help


Keywords
The Utility Area - Keywords

The Keywords drop down box displays the first Keyword of each help topic as you page up or down. Click on the arrow to the right of the drop down box, or press Alt Up Arrow, to display all of the Keywords for the current page. A new Keyword can be entered, at any time. Delete Keywords by highlighting the desired Keyword and pressing the delete key. Click anywhere in the editor or press the Esc key to return to the editor.

Search

Keywords are used by the search function of the Windows help system. Assign Keywords to topics that are a reference to the topic by association. Use synonyms, whenever possible, and attempt to lead the user to the topic with associated words or phrases. There is a maximum of 15 Keywords per page.

Keyword List

Clicking on the button to the left of the Keywords drop down box will pop up a table of Keywords already used in the help file. This is useful if a Keyword is used on a number of pages and you aren't sure how it was phrased or spelled.

Double click on the Keyword you want to add or click on the Accept button and the Keyword will be added to the Keywords drop down box.

There is a maximum of 15 Keywords per page.


Multiple Keywords
The Utility Area - Multiple Keywords

Multiple Keyword tables enable a program to look up topics that are defined in alternate Keyword tables. This feature can be used to provide context sensitive help on words in an editor, for instance.

Multiple Keyword List

Clicking on the button to the left of the Multiple Keywords drop down box will pop up a table of Multiple Keywords already used in the help file. This is useful if a Multiple Keyword is used on a number of pages and you aren't sure how it was phrased or spelled.

Double click on the Multiple Keyword you want to add or click on the Accept button and the Multiple Keyword will be added to the Multiple Keywords drop down box.

There is a maximum of 10 Multiple Keywords per page.


Browse

Clicking on the [image] button will bring up the Browse Group Definitions window.

When first entering Browse Groups, click on the Add button below the Groups list box. Type in the desired name of the group and select OK. Keep group names simple but descriptive. Browse groups define a section of topics, or help pages, that will be displayed as the Browse buttons [image] and [image] are pressed while viewing a Windows help file.

Topics

Browse topics should be related to each other and maintain a degree of continuity while browsing. This allows the user to view related topics without the need to initiate a new search or to return to the Contents page.

Titles

Once a Browse Group name has been entered, you can add the titles of help topics to the Titles list box. When you press this Add button, a list of titles, taken from the current help file, appears. Titles already belonging to a Browse Group do not appear in the list because a topic can belong to only one Browse Group. Highlight the desired title and select OK or double click on the title. The title will be added to the end of list box.

Browse Order

Titles will be Browsed in the order in which they appear in the Titles list box. There are two ways to re-arrange the order of the titles. One is accomplished with the keyboard and the other is done with the mouse.

Keyboard

To move a title with the keyboard, highlight the title to be moved, activate the Move button with the hot key if a mouse is not available, cursor to the new position, and activate the Move button again, which has been renamed to Done, and the title is moved to the new position.

Mouse

To move a title with the mouse, click on the Move button, grab the title with the mouse cursor (press the left mouse button), drag the title to the desired new position, and release the mouse button.

Browse groups or titles contained in Browse Groups can be deleted at any time by highlighting the desired entry and pressing the Delete button under the corresponding list box.


Context Numbers
The Utility Area - Context Numbers

Help Pages

Context numbers can be assigned to help pages, or topics, to provide a context sensitivity link between the help system and your application. The editor will not accept duplicate context numbers for different topics.

Restore

Pressing the Esc key will restore the original contents of the Context Number text box and return focus to the editor.

Auto Context Number

If the Context Number text box is empty, clicking on the right arrow button, next to the Context # button, will cause the Help Magician to automatically enter a Context Number. The number entered will be one greater than the highest Context Number in the help file.

Context Strings

Pressing the Context # button toggles the state of the Context Number/Context String text box. The button displays the current state. In Context Number entry mode, the button reads, Context #. In Context String entry mode, the button reads, Context $.

Mapping

Context Strings are constructed from the topic title or are imported along with an RTF file. Spaces are replaced with underscores and other illegal characters are re-mapped (see Appendix C in the users manual).

Context String Uses

In normal use, it is not necessary to alter Context Strings. However, when editing a Bitmap with SHED.EXE, you will need the name of Context Strings associated with the topic, or page, to be linked. A complete printout of the Context Strings is available by selecting Context Relations from the File/Print Menu. A description of how the Context Strings are constructed from the topic titles is provided in the manual in Appendix C.

Include Files

Another use for Context Strings would be for compatibility with symbolic references to help topics in an Include file, specified in the [MAP] section of the project (.HPJ) file. In this case, you may want to edit the Context Strings so that the references match those in your Include file. If this method is used, the name of the Include file must be entered in the Context String Map text box in Project Options, available from the Build Menu. If a Context String Map file name is provided, the Help Magician will enter the file name in the [MAP] section of the project file each time the help file is compiled.

Auto Context String

If the Context String text box is empty, clicking on the right arrow button, next to the Context $ button, will cause the Help Magician to automatically construct a Context String from the topic title and enter it into the Context String text box.

Title Page

The title page, as selected in Project Options, must have a Context Number. If a Context Number is not assigned at design time, the Help Magician will assign the next available Context Number in order to build the help system.


File Menu
The File Menu

The File Menu provides all of the functions to load and save Help Magician help files. In addition to the file commands, the print functions and exit option are located in the File Menu.

Click on  the desired area of the File Menu for specific help


New

Select New from the File Menu to start a new help file. All the information from the previous file, if any, will be erased. If the previous help was edited but not saved, you will be warned and you will have the option to save the file before the information is erased. Editing begins at page one with the title, "Temp Title 1". The file name will be DEFAULT.HLX.


Open

Existing File

Select Open from the File Menu to read in an existing help file. All of the Keywords, Jumps, Popups, defined fonts, etc. that were saved with the file will be read in with the help text. The 'ROOT' directory for the current help build will be set to the directory from which you load the help file.

Extension

The Help Magician's default file extension is .HLX.


Importing RTF Files

Overview

The Help Magician will read RTF files generated by Word for Windows. RTF files, written by the Help Magician can be read into Word for Windows, edited, and read back into the Help Magician, combining the WYSIWYG editing capabilities of Word for Windows and the functionality of the Help Magician.

Backup

It is important that you backup up your RTF file before reading it into the Help Magician and writing it out again. Because of the filtering that is necessary to import the RTF file into the Help Magician, the file will be changed.

Exporting

To export an RTF from Word for Windows, select "Save As..." from the File Menu. Click on the drop down box labeled "Save File as Type:" and select "Rich Text Format (*.rtf)". Change the file extension to .RTF in the "File Name:" box. This distinguishes the file from a Word for Windows .DOC file and makes it easier to import into the Help Magician because the default extension expected is .RTF.

Importing

To import an RTF file into the Help Magician, select Import RTF from the File Menu. The file extension defaults to .RTF.

The default path for the Help Magician will not be changed to the path from which the RTF file was imported. When you import an RTF file and save the Help Magician's file, you can select another path as the 'ROOT' path for the help build so that the original RTF file will not be overwritten when you build the help system.

Filter

The Help Magician supports most of the RTF commands supported by the Windows help compiler. Commands not supported will be filtered out and written to a report file consisting of the same name as the RTF file, with a .RPT extension, for your reference. Any errors that occur during the importing will also be written to this file.

Origin

There are some differences in the way the RTF file is handled depending on the origin of the help file. The Help Magician writes some additional fields into the footnotes, that is not used by the help compiler, and uses this information when the RTF file is read back into the Help Magician. The following paragraphs describe the differences.

Word Files

Help files originally written in Word for Windows will be read in and the help file specific data, such as Titles, Browse Sequences, Context Strings, etc. will be stored in the Help Magician's database.

Context Numbers

Since Context Numbers are not actually part of the help file, but are included in the project file, help files originating in Word for Windows will not contain Context Numbers. If the help file originated in Word for Windows, you will have to enter the Context Numbers in the Help Magician.

If the help file originated in the Help Magician, or if it has been re-written from the Help Magician, the Context Numbers will be written to an additional footnote field and will be read in and properly stored by the Help Magician.

Context Strings

The Help Magician constructs Context Strings from the topic titles. If, however, you enter Context Strings in the Context String footnote field, in Word for Windows, they will be used by the Help Magician instead of constructing new Context Strings.

Titles

The Help Magician requires that every page have a title. When pages are read in from an RTF file, if a page does not have a title, a title is created for the page. The temporary title consists of the text, "Temp Title" and the number of the page.

Font Styles

The Help Magician uses Font Styles that contain all of the attributes of the marked text. The RTF file defines the typeface and assigns the boldness, style, and color at each occurrence of a font change. If the help file originated in Word for Windows, Help Magician Font Styles will be created with arbitrary names. The assigned names can be edited by selecting the Define Styles function from the Marker Menu. If the help file originated in the Help Magician, the Font Styles originally defined will be written to a Font Style file and read in during an RTF import. All occurrences of font specifications that match a defined style will be assigned to that style. If additional font specifications are used, they will be assigned to a new Font Style.

Save Styles

The Font Styles are saved to a file with a .HLS extension every time an RTF file is written. When an RTF file is imported, the Styles Sheet is read in and existing defined Font Styles are used, whenever possible. Note that Save Styles can be selected from the Marker Menu to save the current Font Style definitions without writing an RTF file.

Browse

If Browse Sequences originated in Word for Windows, the sequence numbers don't necessarily have to be sequential, they can be incremented by any value. When imported into the Help Magician, they will be renumbered so that they are sequential. If the help file originated in the Help Magician, or if the RTF file was re-written from the Help Magician, the sequence numbers will already be sequential.

Version 3.1

While importing an RTF file, if the Help Magician detects codes specific to features supported only by Windows 3.1, the version, stored in the Project Options, will be set to version 3.1.

Related Topics

RTF - Technical Specifications


RTF - Technical Specifications

RTF Format

The Help Magician's RTF Reader supports both Word for Windows and Ami Pro RTF formats at this time. The Project Options menu offers an option to select the version of Word for Windows RTF file written by the Help Magician.  The option defaults to version 2.0, however the user may choose between versions 1.0 and 2.0.

Version 3.1

Only one Win 3.1 feature is fully supported:  segmented and non-segmented hypergraphics. Formatted invisible text is partially supported to provide 3.0 compatibility.

Syntax Checking

The RTF Reader performs WinHelp 3.1 syntax checking.

Warning

There are potential translation problems converting back and forth from Word for Windows versions 1.0 and 2.0 RTF formats. The RTF formats sometimes get garbled and may become unreadable by the RTF Reader.

Errors

RTF Reader errors, unsupported features and unknown or unsupported RTF commands will be written to a report file using the original filename with a .RPT extension.

Critical errors will be displayed on screen as well as written to the report file.

Any invalid references in the original RTF by hotlinks (jumps or popups) to non-existent topics and/or Context Strings will be ignored to the extent that "@" symbols will be placed on either side of the hotlink text. This will aide the user in finding any missing hotlink markers after the RTF is translated. The references and locations within the RTF file will be written to the .RPT file and a  window will appear when the reader has completed to indicate the total number of errors encountered.

NOTE: Since the Help Compiler expects underlined, double underlined and strike through text to represent hot links to topics, any occurrences of these words or phrases will be treated as such and be reported as popups or jumps with missing invisible text.

Browse

Browse Sequences that have been formatted as text instead of numbers will be converted to numbered sequences and the original text will be lost. Please format browse sequences numerically if initial development is done in Word for Windows. Also, numerically formatted browse sequences will be renumbered sequentially and the original numbers will not be saved.

Browse Sequences created in Word for Windows with no group title, i.e. "null list browse sequences", will be assigned to a group entitled "Null" by the RTF Reader.

Fonts

The fonts used in Word for Windows RTF will be converted to Help Magician Font Styles and put in a table. If a table already exists for the project, it will be used and any additional font styles discovered will be added to the table.

When a new style is created, the style name is constructed using the attributes of the font definition. The name consists of the string, "Style #" followed by a sequentially numbered three digit identification, the typeface, point size, the word 'bold', if the font is bolded, 'Italic' or 'Normal', and the red, green, and blue attributes, if defined.

If the number of fonts allowed per page is exceeded for any given page, the remainder of the text on that page will not be formatted.

ROOT

Please keep all associated files for a particular project in the 'ROOT' directory. This includes font style files, bitmaps (if possible) and all the Help Magician created files (HLX, HLS, etc.).

Formatting

Please use one continuous underline, double underline or strikeout formatting for popups and jumps, respectively, in Word for Windows. Breaking up the formatting for hot links may cause problems in translation from Word for Windows versions 1.0 and 2.0 conversion process. Likewise, fonts should be treated in the same way.

Please do not format help text and footnotes ACROSS pages in Word for Windows.

Context Strings

The Help Magician handles Context Strings invisibly to the user. If Context Strings are created in the Help Magician, they are created from the topic title. However, in version 1.1 and later, when they are included in a footnote, they are read into the Help Magician and preserved.

Duplicate Context String names will be adjusted by renaming one with a "_000" tagged onto the end of the string, where the actual number used refers to the particular help page the Context String references.

Missing Context Strings will be created using the help page title for that page. Duplicates will be adjusted using the aforementioned procedure.

Titles

Missing help page titles will be created using "Temp Title ##", where ## refers to the particular help page number.

Footnotes

A footnote will be appended to the first page of the RTF help file that the Help Magician writes out. This footnote will contain information that cannot be coded into the help text, but is required by the Help Magician should the file be re-read. Please do not modify this footnote or its contents.

Hot Links

Improperly used hot links, i.e. jumps, popups, etc., will be ignored by the RTF Reader, but the hot link text will have "@" characters placed around it to make it easier for the user to find them.

Version

The RTF Reader will detect the appropriate version of the Help Compiler to be used for the file being read. It is up to the user to verify the Help Compiler version selected in Project Options.

Limits

The RTF Reader will check  for limits on fonts per page, number of pages, etc. and report them when encountered. In the case of fonts, hot links and indents, the RTF Reader will record any further occurrences, into the report file, of the particular item that the maximum limit has been reached. In the case where the maximum number of pages has been reached, the RTF Read will issue an error message and stop.

Bitmaps

Pictures and bitmaps inserted directly into a Word for Windows RTF document are not supported by the RTF Reader. Please use "bitmaps by reference". Pictures are not supported by the Help Magician.

Miscellaneous

Foreign

The Help Magician provides foreign language and non-standard character support. To type in a character above ASCII 127, simply hold down the ALT key and press a three digit ASCII decimal character code using the numerical keypad.

Limits

The number of jumps per page and popups per page has been increased to 60.

Upgrade

Upgrade of previous versions of the Help Magician files, version 1.01 files to version 1.26, is automatically handled by the Help Magician editor. When an older file is detected by the new program, a message will appear requesting the user to upgrade to version 1.30. Select OK to upgrade the file.


Import Text

ASCII text can be imported in the Help Magician. The text can be written out from a word processor but some formatting is required before it can be read into the Help Magician.

Important

Importing text performs complete initialization of the editor and its related database. Also, the 'ROOT' directory is set to the directory from which the text was imported. To import portions of text, use Windows DDE to cut sections of text from another editor or word processor and paste them into the Help Magician.

Page Breaks

When a word processor file is exported as text, there are no hard page breaks. The Help Magician needs hard page breaks to determine where on help topic ends and another begins.

Page Delimiters

When you write out an ASCII file from the Help Magician, using Save As Text, each page begins with the heading, Title:. The Help Magician considers this to be a page break and will begin a new topic. Optionally, you can enter the sequence, \Page, or a literal character 12, into your ASCII file as a page delimiter. If no page break is included in the ASCII file, the Help Magician will try to place all of the text into the first page, probably resulting in an "out of string space" error.

Other Formatting

Other formatting can be used to facilitate importing ASCII files into the Help Magician. If an ASCII file is formatted in the same manner as the Help Magicians Save As Text command, the information following the headers (\Title:, \Keywords:, \Multiple Keywords:, \Context Number:, and \Browse:) will be written to their appropriate positions in the help file database as if they had been entered from the Help Magician. The headers must be at the left margin with no characters, spaces. or tabs before the header.

TUTOR.TXT

The Tutorial file, TUTOR.HLX, was Saved As Text as TUTOR.TXT. The following listing of the third page, in bold type, shows the exact format of the text file:

\Title: Cutting Text

\Keywords: Clipboard, Cut, Edit

\Multiple Keywords:

\Context Number: 0

\Browse: Edit: Cutting Text, Copying Text, Pasting Text

Cutting Text

Select the text to be cut by holding the left mouse button and dragging over

the text. Then select Cut from the Edit Menu or press Shift Del. The text is

cut to the Windows Clipboard.

Conversions

Most word processors can save a file in ASCII, or text only format. To convert a word processor document to a Help Magician file, modify a version of the document, save the document as text, and import it into the Help Magician with the Import Text function available from the File Menu. Be sure to include one of the page break delimiters (described earlier in Page Breaks) in the text file. You can include any of the other headers shown in the TUTOR.TXT file above or import the text file and enter the information in the Help Magicians editor.

Keep Returns

If possible, don't word wrap the lines in the text file with hard returns. This will cause lines of fixed length in the Windows help system, defeating the automatic word wrapping done by WINHELP.EXE. The Keep Returns option will import the text file exactly as it was written.

Delete Returns

If hard returns are present, select the Delete Returns option from the Import Text Menu. This will remove all hard returns except those at paragraphs, or double spaced lines.


Save

Selecting Save from the File Menu will save the current help file without asking for a file name unless a file name has not yet been established. The default file name, DEFAULT.HLX, is not considered to be a designated file name and you will be asked to provide a file name if you select Save from the File Menu. The 'ROOT' directory for the current help build will be set to the directory to which you save the help file.


Save As

Selecting Save As from the File Menu gives you the option of specifying a file name for the current help file before saving. As described in Save, above, Save As will be called if a file name has not yet been assigned to the current help file. You can also use Save As to save a help file under a different file name than the name that is currently assigned to the file.

Extension

The file extension for a Help Magician file must be .HLX. If you enter an extension other than .HLX, it will be changed to .HLX when saved.


Save As Text

The current help file can be saved as ASCII text, without any of the Markers by selecting Save As Text from the File Menu. This is provided so that the help file can be read into a word processor for a spelling check. This special formatted file can be read back into the Help Magician but none of the special Markers will be retained. If you have already inserted Markers into your help text, you can note the spelling errors and make the changes to the actual help file.

With Header

The title, Keywords, multiple Keywords, context number, Browse Group and the topics included in the Browse Group will be written to the file before the help text on every page. Each section is preceded by a header (\Title:, \Keywords:, \Multiple Keywords: \Context Number:, and \Browse:). The Keywords and multiple Keywords are separated with commas. The Browse Group is separated from the included topics by a colon.

Without Header

Only the caption, Title: and the title is included for each page.


Print

Print Help File

The Print Help File option will send an ASCII only version of the help file to the default printer. The print function assumes the printer is set up for 80 columns of text and that the printer font is a fixed space font. There will be three blank lines, top and bottom, and left and right margins of five characters.

Select the range of pages to be printed and click on Accept.

Print Browse Sequence

The Print Browse Sequence option will print a copy of the current Browse sequences, as defined in the Browse Definitions window, to the default printer. This can be used as a reference when testing the help file, with the Test Mode in the Help Magician, or when viewing the finished help system with WINHELP.EXE.

Context

The Print Context Relations will print a copy of the titles of all the pages in the help file and their corresponding context numbers to the default printer. This is a useful reference when programming context sensitive help into your application or for a reference to the Context Strings when using hot spots in version 3.1 of the help compiler.

Headers

The print function assumes the printer is set up for 80 columns of text and that the printer font is a fixed space font. There will be three blank lines, top and bottom, and left and right margins of five characters. A header, containing the file name, date, time, and page number will be printed on every page.


Exit

This will exit the Help Magician and return control to Windows. You will be warned if the current file has been edited since the last save and you will have the option of saving it before exiting, or to cancel the exit and return to the editor.


Edit Menu
The Edit Menu

The Edit Menu provides functions to cut, copy, and paste text, search for and, optionally replace text, as well as commands to Goto a specified page, insert or delete a page, and reformat text.

Click on  the desired area of the Edit Menu for specific help


Cut
Cut Text

Selecting Text

Select Cut to delete selected text from the editor. Text is selected in the standard Windows manner, by pressing the left mouse button and dragging the mouse cursor over the desired text or, using the keyboard, holding the Shift key while cursoring over the desired text.

Markers

All Markers are removed from the text before it is cut to the Windows Clipboard. The special Markers, used by the Help Magician, are not just marks in the text but the relationship of every Marker is kept in a database and pasting text with Markers that are not referenced in the database would be meaningless.

The automatic syntax checking capabilities of the Help Magician, prevents Cutting highlighted text containing unbalanced Markers. Each Marker (Jump, Popup, Bitmap, and Font) has a starting and an ending character. To delete one without the other would result in errors when the Help Magician writes the RTF file and it is more convenient to catch the problem in the editor. If you attempt to Cut text with unbalanced Markers, you will receive an error message.

Short Cut

While it is not noted in the menu, the standard Windows hot key, Del, can be used to Cut selected text.


Copy
Copy Text

Copying text is accomplished exactly the same as Cutting text except that the text is not removed from the editor. The same rules concerning unbalanced Markers, that apply to Cutting text, apply to Copying selected text. Markers are removed from the text before it is copied to the Windows Clipboard.

The standard windows hot key, Ctrl Ins, can be used to copy selected text.


Paste
Paste Text

Clipboard

Paste will insert the text in the clipboard, if any, at the current cursor position. If text is highlighted, it will be replaced by the pasted text. A message box will notify you if the clipboard does not contain any text.

Markers

If the text to be pasted contains any of the special Markers used by the editor to designate Jumps, Popups, Font Styles, etc. a message box will notify you that pasted text cannot contain Markers. You will then have the option to cancel the paste operation or to continue. If you elect to continue, the text will be pasted and the Markers will be removed.

The Cut and Copy options remove Markers before the text is cut to the Clipboard. However, if the text to be pasted contains any of the special Markers used by the editor to designate Jumps, Popups, bitmaps, Font Styles, etc. (this includes any characters with an ASCII  value of less than 32), a message box will notify you that pasted text cannot contain Markers. You will then have the option to cancel the paste operation or to continue. If you elect to continue, the text will be pasted and the Markers will be removed.

Adding Text

You can use the paste command to add text from other sources using the DDE (Dynamic Data Exchange) capabilities of Windows. Copy the text from another application, switch to the Help Magician, place the cursor at the desired insertion point and paste the text.

The Shift Ins hot key combination can be used in place of the menu item to initiate a paste operation.


Find

Selecting Find from the Edit Menu will bring up the Find dialog.

Find What

The search text can be part or all of a word and it can be case sensitive or case insensitive, depending on the options selected below.

Whole Word

Click on the Whole Word check box if you want to limit the text found to a complete word, with a space or punctuation mark on either side. If the Whole Word box is not checked, the search text can be included in, or part of, a word.

Current Topic

Selecting Current Topic will limit the search to the current help page, or topic.

All Topics

Selecting All Topics will cause the search to be performed on all help pages from the current page foreword.

Case Insensitive

During a case insensitive search, the search text will be compared with the text being searched without regard for case. Both are converted to upper case before comparison.

Case Sensitive

In a case sensitive search, the text must match exactly, with regard to the case of each letter in the search text, entered in the Find What text box.


Find Next

Find Next will find the next occurrence of the search text, based on the arguments previously entered in the Find form. The search begins at the cursor and ends at the bottom of the last page. The search will not wrap to beginning of the help file. If Find Next is selected and there has not been an initial search, the Find form will pop up.


Find Previous

Find Previous will find the previous occurrence of the search text. If there has not been an initial search, no action will be taken. The search begins at the cursor and ends at the top of the first page in the help file. The search will not wrap.


Replace

Options

Because there are more options, Replace uses a different form than Find. In addition to the Find form, you must enter a replacement text string. Also, there are options to verify each replacement or to replace all occurrences. If you select Verify, you will have the option, at each occurrence, to replace the text, leave the text as is, or to cancel the search and replace. In verify mode, Replace begins at the current cursor position on the current page. It does not wrap to the beginning of the file.

Replace All

This option will cause the Help Magician to scan the entire help file, starting at page one, replacing all occurrences of the search text, based on the Case Sensitivity and Whole Word options. The editor will return to the page you were editing when Replace is complete.


Goto Title

This function allows you to Jump directly to a particular page, which you select from a list of titles. You can also goto a page by entering the page number in the text box to the right of the Page: label, in the Status Bar.


Insert Page

Insert Page will insert a page, at the current page number, moving all pages, from this page number, forward one page. The new, inserted page, will have the same attributes as a new page that is created by clicking on ^PgDn while on the last page. The title will be Temp Title plus the page number. A page cannot be inserted if the insertion would cause the number of pages to exceed the maximum number of pages allowed for a help file.


Delete Page

This will delete an entire page from the current help file. If there are Markers in the text on this page, they also will be deleted. If other pages are linked to the page to be deleted, the pointers to this page will be deleted and the Markers will be converted to the '@' symbol, for your reference. If the last page is deleted and was the Help Index Page, then the first page will default to the new Index Page, otherwise the new Help Index Page will be the next consecutive page.


Reformat Text

The editor word wraps and reverse word wraps, in most instances, but, if it does not reverse word wrap on deletion of text, you can select Reformat Text or press Ctrl R to reformat the text.


Editor Menu
The Editor Menu

The Editor Menu allows customization of the font typeface, size, and boldness in the Help Magician's Editor.

Click on  the desired area of the Editor Menu for specific help

INI File

The editor options, font name, size, and boldness, are stored in a file called HLPMAGIC.INI. This file is created during installation and is read into the Help Magician each time you run the program. When you exit the program, the file is rewritten, to save the current settings. The path to your word processor is also stored in the INI file. Options specific to each help file are stored in the help file.


Editor Font
Editor Font Name

Selecting Font from the Editor Menu will cause the menu to extend to the right and display the Typeface Menu. The currently selected font will be preceded by a check mark. Click on the desired font and the menu will return to the Editor Menu.


Editor Font Size

Selecting Size from the Editor Menu will cause the menu to extend to the right and display the font size options for the help editor. The currently selected font size will be preceded by a check mark. Click on the desired size and the menu will return to the Editor Menu.


Editor Font Bold

Selecting Bold from the Editor Menu will toggle the boldness of the editor text. The default is bold and the menu item is preceded by a check mark. Click on the menu item to turn bold on and off.


Build Menu
The Build Menu

The Build Menu contains all the options commands necessary to build and view a Windows help file.

Click on  the desired area of the Build Menu for specific help


Project Options

The Project Options dialog contains all of the options that you can set for the Windows help compiler.

Warning Level

Select the warning level for the Windows help compiler.

Severe: Only the most severe warnings

Intermediate: An intermediate level of warnings

All: All warnings.

Compress

Select whether to have the help compiler compress the help file. Compressed help files are smaller but require more time to compile. You may want to turn Compress on for the final version.

Index Page

Select the page that will be displayed first as the Help Index when the help system is viewed under WINHELP.EXE. If no Index Page is selected, then the first page of the help file will be used as default.

Compiler Path

Enter the full drive, path, and executable name to your Windows compiler. The path and defaults to C:\WINDEV\ but it can be changed at any time. The Compiler Path is stored with each help file so that help files can be individually created for different versions of Windows.

Word Processor Path

Enter the full drive, path, and file name to the word processor that you will use to view the RTF files generated by the Help Magician. If you don't have a word processor that will read RTF files, enter 'None' in this box. See Call Word Processor for more detailed information.


Write RTF File

This option will write the RTF file, needed by the Windows help compiler, to the 'ROOT' directory for the current help build. If the help file has not been saved since the last edit, you will have the option to save it. You will be informed if the RTF file is up to date and the Help Magician will not rewrite the file if it is current. You can over-ride time and date stamp checking by selecting Rebuild All from the Build Menu.

Important

If an Index Page has not been selected, then a warning message will appear indicating that page #1 of your help file will be used as a default index. Select OK to continue or Cancel to return to the editor.

If there are missing delimiters within numbered indents, then warning messages will be displayed as well. Select OK to continue or Cancel to return to the editor.


Run Compiler

Run Compiler calls the Windows help compiler, in the path specified in the Compiler Path option. If the current help file has not been saved since the last edit, you will have the option to save it. If the RTF file needs to be updated, you will have the option to update it at this point.

To prevent a mismatch between the help file and the compiled help system, the Help Magician will not compile the files until all of the components are up to date. Again, you will be informed if the help system is up to date and, if so, it will not be re-compiled. You can over-ride time and date stamp checking by selecting Rebuild All from the Build Menu.

Messages

In version 3.0 of the Windows help compiler, the output messages are directed to a file and the Help Magician displays the contents of the file in a window when compilation is complete. In version 3.1, the ERRORLOG option is used in the project file and the file is displayed in a window when compilation is complete. This allows scrolling back and forth through the messages instead of trying to view them as they scroll by on the screen. The messages can be sent to the default printer by clicking on the Print button.

PIF File

A Windows PIF file (HCBAT.PIF) is written to the help compiler directory to control the operation of the help compiler. If a PIF file already exists in the help compiler directory, it will not be overwritten. This is done so that the PIF file may be customized for the target system, for instance: To run the Help Magician in Standard mode, try reducing the amount of memory allocated to the help compiler, in the PIF file.


Rebuild All

Rebuild All rebuilds all files in the current help system without regard for the time and date stamp on the files. This includes writing the RTF file and calling the help compiler.

Related Topics

Write RTF file

Run Compiler


Syntax Checking

Purpose

Syntax Checking performs dynamic checking of Markers as the RTF file is written. If a Marker error is detected, the error will be displayed in a message box and the text will be highlighted for reference. Correct the error and re-write the RTF file. Note that the RTF file is also written when Rebuild All is selected and when Run Compiler is selected and the RTF file is not up to date.

Option

Syntax Checking defaults to "Checked" or "On" and should be left "On" unless it prevents compiling a help file that cannot be corrected. If a help file is compiled with Syntax Checking "Off", it is possible that there will be errors in the help file when viewed with WINHELP.EXE.


View Links

Selecting View Links will display a window with a list of all the topics in the help file and all of the Jumps and Popups. The form can be maximized to view more of the list at a time and the list can be scrolled horizontally and vertically.

Done/Print

Click on the Done button to close the window or click on the Print button to send a copy of the list to the default printer. The print function assumes the printer is set up for 80 columns of text and that the printer font is a fixed space font. There will be three blank lines, top and bottom, and left and right margins of five characters. A header, containing the file name, date, time, and page number will be printed on every page.


Call Word Processor

Select Call Word Processor to invoke the Word Processor specified in the Project Options window, with the RTF file pertaining to the current help file. This can be used to preview the text formatting of the help file without compiling the file.

Important

Note that the specification in the Project Options window must include the complete drive, path, and executable file name, such as:

C:\WINWORD\WINWORD.EXE.

Your word processor must be able to accept a file name with a .RTF extension as a command line argument. If it does not, load your word processor and read in the RTF file by selecting the appropriate options from the File Menu.

If the word processor is open at the time and a copy of the file is one of the windows, the word processor may open a second version of the RTF file. To avoid this, either close the windows containing the RTF file or close the word processor each time you return to the Help Magician.


Call WINHELP.EXE

This will call WINHELP.EXE and display the compiled help system as your end users will view it.

The Help Index will be displayed. If you have recently re-compiled the help system, you may encounter a "Help File Changed" message from Windows Help. Select OK and select Call WINHELP again.


Marker Menu
The Marker Menu

The Marker Menu provides all the functions necessary to establish Jumps, Popups, help font definitions, and to link bitmaps into your help system. Each Marker consists of a starting and an ending Marker. The appearance of the Marker characters varies from one font to another and from one screen resolution to another. They can be represented as a vertical bar or as a round bullet. In any case, they are easily recognizable as the only non ASCII characters in the text.

Click on  the desired area of the Marker Menu for specific help

Selecting Text

Single words or phrases can be selected and marked. Text for all of the Marker types is chosen in the same manner and the selection procedure is quite liberal.

If the cursor is on any part of a word, or the space before a word, the entire word is included when the Marker is selected. If text is highlighted, the highlighting need not cover the entire phrase from beginning to end. The Marker will be placed in front of the first word in the phrase and at the end of the last even if they are not completely highlighted.

Punctuation

Any punctuation mark will be considered a word delimiter and Markers will be placed inside the punctuation except for punctuation inside highlighted text. If the automatic Marker placement doesn't produce the results you want, simply edit the text and/or punctuation after the marker has been placed.

Related Topics

Marker Errors


Jump

Select Jump from the Marker Menu to set up a Jump, or link, between the selected word or phrase and another help topic. When you select Jump, you will select the title of the page to Jump to from a list of available titles. In the finished help system, the user will Jump to the selected page when they click on the word or phrase. The current page is not included in the list because it would not be a valid Jump link.

Hot Spots/Hypergraphics

To define a Jump, associated with a Bitmap, place both Bitmap and Jump Markers around the Bitmap file name. For Hot Spots, or Segmented Hypergraphics, edit the Hot Spots with SHED.EXE, included with version 3.1 of the Windows SDK package, and place the Markers around the .SHG file name.

When editing a Bitmap with SHED.EXE, you will need the name of Context Strings associated with the topic, or page, to be linked. A complete printout of the Context Strings is available by selecting Context Relations from the File/Print Menu. A description of how the Context Strings are constructed from the topic titles is provided in Appendix C.

Jump Limit

There is a maximum of 120 Jump Markers per page.


Popup

Selecting Popup will establish a link between the selected word or phrase and another help page, or topic. A Popup is used primarily for definitions of words or as an explanation of a phrase. When run under WINHELP.EXE, the contents of the linked topic will be displayed in a window which pops up over the current help topic. The user will not Jump to the selected topic page.

When you have selected the text to be marked, you will select the linked topic from a list of titles. The current page will not be included in the list as this would not be a valid Popup.

Hot Spots/Hypergraphics

To define a Popup, associated with a Bitmap, place both Bitmap and Popup Markers around the Bitmap file name. For Hot Spots, or Segmented Hypergraphics, edit the Hot Spots with SHED.EXE, included with version 3.1 of the Windows SDK package, and place the Markers around the .SHG file name.

When editing a Bitmap with SHED.EXE, you will need the name of Context Strings associated with the topic, or page, to be linked. A complete printout of the Context Strings is available by selecting Context Relations from the File/Print Menu. A description of how the Context Strings are constructed from the topic titles is provided in Appendix C.

Popup Limit

There is a maximum of 60 Popup Markers per page.


Font Style

Select Font Style to mark a word or any amount of highlighted text as a pre-defined font style. In the finished help system, the text will be displayed to the specifications of the defined style. The Status Bar, above the editor, continuously displays the attributes of the current font style.

Font Limit

There is a maximum of 60 Font Markers per help page.

Related Topics

Define Styles


Bitmap

Select

Select Bitmap to mark a file name, embedded in the help text, to display a graphic image in the compiled help system. Text selection is different for bitmap Markers than for Jump, Popup, etc. Since a bitmap, in the help text, is a file name, the search for the beginning and end of words ignores punctuation so that the period before the file extension, back slashes, etc. can be included in the file name.

Path

If a path is not included in the bitmap file name, the bitmap must be located in the 'ROOT' directory for the current help build. If a path is specified, it will be written into the project file for the Windows help compiler.

Auto Bitmap

If Bitmap Marker is selected with the cursor on a space, the File Selection form is provided to select a Bitmap from the hard drive. When selected, the Bitmap filename is entered into the editor and the Bitmap orientation form pops up to select character, left, or right justification.

Preview

When selecting Bitmaps, in the File Selection Form, the image may be previewed by highlighting the filename, in the Files: box, and clicking on the Preview button.

Bitmap Limit

The number of Bitmap Markers in a help system is unlimited.


Indent

Selecting Indent, from the Marker Menu, or pressing the hot key, Ctrl I, will bring up the Indent form. There are several types on indent options available from the Indent form.

Indent Only

By default, the Bulleted Listing checkbox is unchecked. In this mode, a paragraph, or group of paragraphs, can be indented by the amount specified in the indent text box at the top of the form. The controls that pertain to Bulleted Listings are disabled in this mode.

Paragraph

To indent a single paragraph, place the cursor anywhere in the paragraph and select the Indent Marker, or press Ctrl I. Enter the amount of indentation, in inches, and select OK.

Block

To indent more than a single paragraph, highlight the text to be indented and select Indent from the Marker Menu. The text need not be entirely highlighted. The Help Magician will find the beginning and end of the paragraphs automatically.

Rounding

A decimal portion of an inch is allowed but it will be rounded to the nearest hundredth of an inch, if specified to more than two decimal places.

Indent Limit

There is a maximum of 20 Indent Markers per help page.

Minimum Indent

There is a minimum left indent of .08 inches maintained at all times throughout the help document to properly align tabs. This will not affect any indentation set greater than the minimum.

Bullets

To create a bullet listing, check the Bulleted Listing box by clicking on it with the mouse. This enables the Bulleted Listing options on the form. Select the type of bullet in the radio button frame (square or numbered). If square is selected, the bullet will be automatically placed in the text at compile time. Enter the bullet position, in inches. The bullet will be indented by the amount specified and the text will be indented further by the amount specified in the indentation text box. The text will be indented, beyond the bullet, regardless of the word wrap, when viewed with WINHELP.EXE. Blank lines will not be bulleted.

Numbered Lists

Numbered Lists can be created by selecting the Numbered radio button in the Bullet Style frame. In this case, you can enter a number, letter, or any character you wish into the text and it will be formatted as if it were a bullet list. You can use numbered conventions such as:

1	Item one.

2.	Item two.

3)	Item three.

A.)	Item A

Words

Numbered Lists can also be created using words or phrases in place of the number character. If words are used, the rules are the same as for lists with numbers. If phrases are used, there can be spaces between words but the indent must be separated from the phrase by a Tab character.

Important

There MUST be a space or a tab between the number (or other character) and the text. Be sure that the specifications for the bullet indent and the text indent do not cause an overlap of text.

Note

In order to produce indented non-numbered paragraphs after a numbered paragraph, you may intentionally leave out the number before the delimiter to achieve this effect:

1.	This is an example of the first paragraph that is word wrapped.

This is the next paragraph with no numbers or text before the space or tab delimiter.

2.	This is the next paragraph with a delimiter.

Indent Calculation

The paragraph position for Numbered Lists are calculated for you by the Help Magician. This is accomplished by simply finding the widest text bullet (which can also be a word or a phrase), adding its width plus the width of one space to the bullet position. You will not be allowed to decrease the suggested indent position less than the widest text bullet plus bullet position. This would cause the indented paragraph text to overlap some of the bullet text, which would not look correct.

Delimiter

The Help Magician looks for a tab delimiter first. If it cannot find a tab, then the first space in the sentence is used as a delimiter. Any consecutive spaces after the first one will be ignored when formatting the paragraph text. It is advised that if you are using phrases as bullet text, that you use a tab as a delimiter instead of a space. If no tabs or spaces can be found in any particular sentence, an error message will be raised. If you choose to continue at this point, the sentence will be indented to the bullet position.

Modify

Indents or Bulleted Lists can be viewed or modified by selecting View/Modify from the Marker Menu.


View Modify
View/Modify Markers

When the cursor is on a word or phrase that is enclosed an any of the special Markers, used by the Help Magician, the values assigned to the text can be viewed or modified. For instance, if the cursor is on a Jump word (the Status Bar displays 'Jump') selecting View/Modify from the Marker Menu will pop up the list of topic titles, from which the 'Jump to' page was chosen, with the highlighted bar on the title on the title that is currently linked to the Jump Marker.

At this point, you can select Cancel or you can change the page to which the Jump word is linked and select OK. Use the same procedure to view or modify other Markers.


Marker Errors

Errors

Error messages will pop up if you attempt to assign a Marker to text that already has a Marker. Font Markers can be nested with Jump and Popup Markers. Indent Markers can be nested with any other Markers except left or right justified bitmaps. Font Markers cannot, however, be nested with Bitmap Markers. Bitmap Markers can be nested with Jump or Popups, for the purpose of creating a Bitmap link (available only with version 3.1 of the help compiler). Jump and Popup Markers cannot coexist.

Unbalanced Markers

Errors will be reported if you attempt to delete a block of highlighted text that contains unbalanced Markers. Markers must be deleted in pairs, including both the starting and ending Markers. Be sure that all occurrences encompass both Markers in the selected text.

Invalid

An error will be reported if you ask to delete a Marker but the cursor is not in a valid position. The cursor must be between two Markers, just to the left of a Marker, or the highlighted text must include a Marker.


Define Styles

Selecting Define Styles brings up the Font Style Definition window. Up to 600 Styles can be defined for the help system.

Default Font

The first style on the list is the default font for the entire help system. All text will be viewed in this style unless it is specifically marked as another style. After the end font Marker, text reverts to the default style. The Default Help Text style cannot be deleted and the name cannot be changed.

Actual Sample

As you cursor through the list, or click on a style name, a sample of the actual font is displayed at the bottom of the window.

Other Defaults

Two other font styles are provided. The first is defined as a font for topic headings and the second is defined as a font for emphasized help text. Both of these may be re-defined or deleted if desired.

Style Name

To change the style name, tab to or click on the Defined Style Name text box and edit the name.

Modify

To modify the attributes of a defined style, click on the Modify button or double click on the style name in the list box. This will bring up the Set Font Properties window.

Font Face

The list of typefaces provided in the combo box includes the fonts shipped with Windows:

Arial (3.1)

Courier 10, 12, 15

Courier New (3.1)

MS Sans Serif 8, 10, 12, 14, 18, 24 (formerly Helv)

Modern

Roman

Script

Symbol 8, 10, 12, 14, 18, 24

MS Serif 8, 10, 12, 14, 18, 24 (formerly Tms Roman)

Times New Roman (3.1)

Important Note

The True Type fonts, supplied with Windows 3.1 are only listed if version 3.1 is selected in the Project Options dialog. Font Faces other than those provided in the drop down box can always be typed into the text box at the top of the list.

Using only these fonts will ensure that your help system will look the same on all target systems. If you use fonts other than those shipped with Windows, substitutions may be made that will cause an unpredictable appearance. The ability is provided, however, to type in the name of a typeface other than those listed.

Font Size

The same is true for Font Size as the Font Face in regard to the fonts shipped with Windows. Select a size from the list or type in a size.

Font Style

Select whether you want the font to be Normal or Italic.

Font Color

Three sliding bars are provided to set the red, green, and blue levels for the font color. As you move the bars with the mouse, the text in the frame labeled Sample Text shows the actual color of the font. You can also type in the values in the text boxes to the left of each sliding bar, from 0 to 255. Font colors default to black with the red, green, and blue levels set to 0.

Limit

There is a limit of 600 defined styles in a help system.


Save Styles

You can save your font style definitions to a file, to be used in other help files. Select Save Styles from the Marker Menu and assign the file a name in the file form. The default extension for styles is .HLS.

Related Topics

Load Styles


Load Styles

When you start a new help file, you can load styles that were defined for another help system. The file form will prompt for files with the default extension for styles .HLS. You can only load defined styles in a new help file.

Related Topics

Save Styles


Help Menu

The information in the Help Magician's own help system will be somewhat parallel to the information provided in the manual. The obvious difference is the ability to display the information in hypertext form.

Click on  the desired area of the Help Menu for specific help


Help Contents
Contents

Selecting Contents from the Help Menu will display the Help Magician's own help system, at the table of Contents page. From this page, you can get more information on any topic by clicking on the desired word or phrase. You can also select Search to search for help on a topic by keyword.


Help Search
Search

Selecting Search from the Help Menu will bring up the help system in Search mode.


Help Keyboard
Keyboard

Selecting Keyboard from the Help Menu will bring up the help system with keyboard definitions as the current topic.


Help On Help

Displays Windows "Help On Help" help file. Gives users instruction on using Windows help systems.


Help About
About

Selecting About sub menu will display the application logo, the Windows operating mode, the amount of free memory available to Windows, and the version number of the Help Magician.


Test Mode

The Help Magicians Test Mode is an invaluable, time saving, tool in the development of your help system. You can instantaneously test the help file without the need to write the RTF file or to compile the RTF file with the Windows help compiler. Jumps, Popups, Browse sequences, and Keyword links can all be tested in Test Mode.

Click on  the desired area of the Test Mode Bar for specific help


Test Contents
Test Mode - Contents

Clicking on the Contents button causes the help system to display the first page in the help file.


Test Search
Test Mode - Search

The Search function works exactly like the Search function in WINHELP.EXE.

Keywords

The upper list box contains all of the Keywords in the help system. As you enter text into the text box, above the Keyword list box, the highlighted bar moves to the Keyword that matches the text entered. As you delete characters, the process reverses.

You can select a Keyword by highlighting the entry in the Keyword list box and clicking on the Show Topics button or by double clicking on the Keyword entry itself.

Topics

When you have selected a Keyword, the titles of the pages linked to the Keyword appear in the Topics list box. Select the topic by double clicking on it or by clicking on the Go To button. The selected help topic will be displayed and History and Back will be updated.


Test Back
Test Mode - Back

Back

The Back button will only be enabled if there are topics in the Back buffer. When you press the Back button, the help system will back up or retrace the steps you took to get to the current topic until the first topic has been reached. At that point, the Back button will again be disabled. The Back buffer will store up to 100 help topics.


Test History
Test Mode - History

Clicking on the History button will pop up a window containing a list of the topics you have visited. A total of 40 (actually 41, including the Contents page) will be stored in reverse order. The most recent topics are listed first. Double clicking on a topic causes the help system to display that topic. Clicking anywhere else on the form, or pressing the Esc key, closes the History window.


Test Browse
Test Mode - Browse

The [image] and [image] Browse buttons will be enabled and disabled to reflect the ability to Browse in either direction based on the Browse sequences set up in the Browse function while designing the help system.


Test Bitmap
Test Mode - Bitmap

The Bitmap button will only be enabled if the cursor is on a file name enclosed in bitmap Markers. If the file exists, in the 'ROOT' directory for the current help build, or the path is included in the file name in the help text, the bitmap will be displayed. Click anywhere on the Help Magician main window to close the Bitmap Viewer.

Note

Bitmaps cannot be displayed in a Popup Window. They can only be displayed when the topic is the current help page.


Test Jump
Test Mode - Jump

The Jump button will only be enabled if the cursor is on a word or phrase surrounded by Jump Markers. When the button is enabled, clicking on it will cause the help system to Jump to the page that was linked to the Jump word or phrase in the design mode of the Help Magician. The History window and the Back button are updated.


Test Popup
Test Mode - Popup

The Popup button will only be enabled if the cursor is on a word or phrase that is surrounded by Popup Markers. When the button is enabled, clicking on it will pop up a window, similar to the window used by WINHELP.EXE, displaying the definition (actually the contents of a linked page) in the window. Since this does not constitute changing help topics, neither the History buffer nor the Back button are updated.


Test Design
Test Mode - Design

Click on the Design button to return to the design mode of the Help Magician.


Tool Bar

The Tool Bar includes many of the functions from the Marker Menu, the Test Mode button, the Browse Definitions button, and the Page Up and Page Down buttons.

Click on  the desired area of the Tool Bar for specific help


Page Up
^PgUp

The ^PgUp button causes the editor to display the previous page, if there is one. You can also display the previous page by pressing the Ctrl PgUp key combination.


Page Down
^PgDn

The ^PgDn button causes the editor to display the next page in the help file, if there is one. You can also display the next page by pressing the Ctrl PgDn key combination. The ^PgDn button is also used to create a new page. If you press ^PgDn on the last page of the help file, the editor creates a new page with a temporary title that consists of the text, "Temp Title" and the actual page number.

The page is not considered edited and will not be saved with the help file until the page has been edited. Another new page cannot be created until the most recent new page has been edited.


Marker Definition
Markers

A Marker is a non-ASCII character, placed in the text by the Help Magician, that denotes a Jump, Popup, Font Style, Indent, or Bitmap to be included in the help system.


Hot Key Definition
hot key

A hot key is a single key or key combination used to execute a menu option. The keys are usually function keys or Ctrl key combinations.


ROOT Definition
ROOT

The ROOT directory, for a help build, is any directory designated as the directory containing the files necessary to build and compile the Windows help file. To the Help Magician, this is the directory from which the help file is opened or the directory to which the help file is saved.


RTF Definition
RTF

An RTF, or Rich Text Format file, is a file format that permits sharing text formatting between various word processors. This is the type of file required by the Windows help compiler.


Help File Definition
Help File

When referred to as a help file, this refers to the Help Magicians .HLX editor file. When referred to as a Windows help file, this refers to the Windows .HLP file.


How To
How To...

Create Jumps

Create Popups

Include Bitmaps

Create Bitmap Jumps

Create Multiple Hot Spots

Indent Paragraphs

Specify Fonts

Change Markers

Delete Markers


Create Jumps

Select Text

To create a link or a Jump from a word or phrase in one topic to another topic, first select the word or phrase that will be displayed as Jump text. By default, this will be seen as green, underlined text under WINHELP.EXE. When the user clicks on the Jump word, WINHELP will display the linked topic.

If the Jump text is a single word, the cursor can be anywhere in the word or it can be anywhere from partially to completely highlighted. If the jump text is a phrase, containing more than a single word, the text must be highlighted from the first word to the last word in the phrase. The highlighting does not have to completely cover the first and the last words. The Help Magician will locate the beginning and the ends of the words for you, making it easier to select the phrase.

Jump Button

Once the Jump text has been selected, click on the Jump button in the Tool Bar at the bottom of the Help Magician's main window. You can also select Jump from the Marker Menu or press the Ctrl J key combination.

Select Topic

A table of topics will be displayed from which you will choose the topic for this Jump. The current page will not be in the table as it would not make sense to jump to the current topic. Click on the Accept button or double click on the topic in the table. Markers will appear on each side of the selected word or phrase and the page number to which the link has been established will be displayed in the Status Bar.


Create Popups

Select Text

To create a link or a Popup from a word or phrase in one topic to another topic, first select the word or phrase that will be displayed as Popup text. By default, this will be seen as green, dotted underlined text under WINHELP.EXE.

If the Popup text is a single word, the cursor can be anywhere in the word or it can be anywhere from partially to completely highlighted. If the Popup text is a phrase, containing more than a single word, the text must be highlighted from the first word to the last word in the phrase. The highlighting does not have to completely cover the first and the last words. The Help Magician will locate the beginning and the ends of the words for you, making it easier to select the phrase.

Popup Button

Once the Popup text has been selected, click on the Popup button in the Tool Bar at the bottom of the Help Magician's main window. You can also select Popup from the Marker Menu or press the Ctrl P key combination.

Select Topic

A table of topics will be displayed from which you will choose the topic for this Popup. The current page will not be in the table as it would not make sense to Pop Up the current topic. Click on the Accept button or double click on the topic in the table. Markers will appear on each side of the selected word or phrase and the page number to which the link has been established will be displayed in the Status Bar.


Include Bitmaps

Method One

One way to include a bitmap in your help file is to type the file name of the bitmap into the editor and then to place Bitmap Markers around the text. If the Bitmap is in the help build 'ROOT' directory (the directory that contains the Help Magician source files), the file name is sufficient. If it is in another directory, the entire path must be included with the file name. After entering the filename, place the cursor anywhere in the Bitmap file name and click on the Bitmap button in the Tool Bar. You can also select Bitmap from the Marker Menu or press the Ctrl B key combination.

Method Two

The second method to include a Bitmap is to click on the Bitmap button in the Tool Bar and select the Bitmap file name from a file list form. When the file form is used to select Bitmaps, a "Preview" button is added to the form. When a bitmap is highlighted, it may be viewed by clicking the "Preview" button. To include the Bitmap in the help file, double click on the file name or click on the Accept button.

When a Bitmap is included with this method, the entire path is included in the file name in the help source.

Justification

When you place Bitmap Markers around a file name, you must select the type of justification for the Bitmap when displayed with WINHELP.EXE. Left and right justifications react just as you would expect. Character justification makes the Bitmap behave as if it were a character. It will maintain it's position in a paragraph and will word wrap as necessary.


Create Bitmap Jumps

Markers

To create a Bitmap Jump, first mark the Bitmap file name as described in Include Bitmaps and then add Jump Markers around the file name as described in Create Jumps.

When a Bitmap Jump is displayed with WINHELP.EXE, clicking on the Bitmap has the same effect as clicking on Jump link text.


Create Multiple Hot Spots

SHED

SHED.EXE is required to create multiple hot spots, or segmented hypergraphics. SHED.EXE, Microsoft's HotSpot Editor, is supplied with The Microsoft Software Development Kit (SDK) and the Visual Basic 2.0 professional version.

In SHED.EXE, import the .BMP file to be converted and define the desired hot spots by holding the left mouse button and 'dragging' to outline the hot spot area. Select Attributes from the Edit Menu and enter the Context String associated with the page to be linked. Save the file with a .SHG extension.

In the Help Magician, enter the name of the .SHG file, where the Bitmap is to be placed, in the editor. Mark the filename with Bitmap Markers and the help compiler will make the appropriate links, using the Context Strings as a reference.

Context Strings

The Context Strings, associated with each page can be printed from Help Magician's File/Print/Context Relations menu. The Context Strings are also listed in the project (.HPJ) file, generated by the Help Magician.

The Help Magician constructs Context Strings from the topic titles. If there are no illegal characters in the title, the only change from the title is that spaces are replaced with an underscore (see Appendix C). Remember that, as the title is changed, the Context String is also changed and any references to the original Context String, in SHED.EXE, must also be changed.


Indent Paragraphs

Select Text

Selecting text for indentation is a little different than for other types of markers. Indentation must be done by paragraph rather than by word or phrase. To indent a paragraph, the cursor can be any where in the text and highlighting is not necessary for single paragraphs. If more than on paragraph is to be indented, highlight from anywhere in the first paragraph to anywhere in the last paragraph. The Help Magician automatically finds the beginning and end of paragraphs.

Markers

Click on the Indent button in the Tool Bar at the bottom of the main window or select Indent from the Marker Menu, or press the Ctrl I key combination. The Indent Marker window will pop up.

Indent Only

If the entire paragraph is to be indented, enter the desired indentation in the text box labeled "Indent in Inches" and click on OK.

Bulleted

To create a bulleted indent, click on the "Bulleted Listing" check box. This will enable the bullet style options. The square bullet will be selected by default.

Square

For a square bulleted paragraph, enter the distance from the left margin for the bullet in the "Enter bullet Position in Inches:" text box. Enter the left margin for the text in the "Enter Indent in Inches:" text box. Click on the OK button and the Markers will be placed around the paragraph or paragraphs.

Numbered

In the Help Magician, a numbered listing can also be a hanging indent using a word or a phrase. To create a numbered listing or hanging indent, click on the "Numbered" radio button.

Delimiter

There must be a delimiter between the left justified text and the hanging indent text. If a single word numbered listing or hanging indent is created, a space will serve as the delimiter. If multiple words are used, the delimiter must be a Tab character. Type the phrase, enter a Tab character by pressing Ctrl Tab, and enter the hanging indent text.

Enter the indent for the entire paragraph in the "Enter bullet Position in Inches:" text box and the position for the hanging indent text in the "Enter Indent in Inches:" text box. In the case of a numbered listing, the label to the left of this text box will be "Suggested Indent in Inches:" until a value has been entered. This value is calculated so that the hanging indent text is indented one space more than the "bulleted text", based on the default help text font.

More Info

See the Marker Menu for more information and examples.


Specify Fonts

Select Text

To specify the font for a portion of help text, first select the section of text to be modified.

If the text to be modified is a single word, the cursor can be anywhere in the word or it can be anywhere from partially to completely highlighted. If the text to be modified is a phrase, containing more than a single word, the text must be highlighted from the first word to the last word in the phrase. The highlighting does not have to completely cover the first and the last words. The Help Magician will automatically locate the beginning and the ends of the words for you, making it easier to select the phrase.

Styles

To change the font style, typeface, color, boldness, italic, or size, click on the "Font" button in the Tool Bar, select "Font" from the Marker Menu, or press the Ctrl F key combination. Select the desired font from the table of "Defined Font Styles". The Help Magician has three defined font styles: "Default Help Text", "Topic Heading", and "Emphasized Help Text". These font styles can be re-defined and new font styles can be added. See "Define Styles" in the Marker Menu chapter for more information.


Change Markers

View/Modify

To view or change the current values of any marker, click on the "View" button in the Tool Bar, select View/Modify from the Marker Menu, or press the Ctrl V key combination. In the case of nested markers, place the cursor to the left of the desired marker as determined by the text in the "Status" label in the Status Bar just above the Tool Bar. Re-enter the desired values just as you would to create the Marker initially.


Delete Markers

Delete

Markers cannot be deleted as normal text, with the delete or backspace keys. They must be deleted with the Delete Marker function. This function is available by clicking on the "Delete" button in the Tool Bar, selecting "Delete" from the Marker Menu, or by pressing the Ctrl D key combination. For single Markers, the cursor can be anywhere in the text between the Markers. For nested Markers, place the cursor to the left of the desired marker as determined by the text in the "Status" label in the Status Bar just above the Tool Bar.

Delete Text

You can delete any portion of text by highlighting the text and selecting "Cut" from the Edit Menu. If the selected text contains Markers, the highlighting must include the starting and ending Markers for any Marker definitions. If the highlighting contains unbalanced Markers, you will not be allowed to delete the text.